NanoVDB: support single-space device buffers in GridHandle (CUDA) - #2288

🚩 issue: I traced the consumers of the device-parse path, and I believe this new validation breaks tools::cuda::addBlindData for grids that came out of a multi-grid handle. addBlindData copies the source grid's GridData header verbatim (including mGridIndex/mGridCount) into its new single-grid buffer and never normalizes them before constructing GridHandle<BufferT> (AddBlindData.cuh:131, a device-only buffer, so it takes this path). With a source grid from handle.deviceGrid<T>(n) of a multi-grid handle: for n > 0 the first iteration throws "inconsistent grid index/count" (mGridIndex != 0), and for n == 0 with mGridCount > 1 the walk runs past the single-grid buffer and throws "grid chain exceeds the device buffer". The old parse accepted these buffers (albeit with OOB metadata reads — which is exactly the hole this validation fixes).

I think the fix belongs in addBlindData rather than in weakening the validation: normalize the header to index 0 / count 1 before constructing the handle, the way splitGridHandles does with detail::updateGridCount<<<1,1>>>. Might also be worth a quick audit for any other tool that constructs a device-parse handle from a copied header.

Fixed in 5ea0b9e — normalized to index 0 / count 1 inside the existing header-fixup kernel (ahead of the tool's checksum recompute, which covers the change). Your audit hunch was right: indexToGrid copies the source header the same way (*dstGrid.data() = *srcGrid.data() and then patches only mGridType/mData1), fixed in the same commit. The other handle-returning tools are clean — the topology ops and MeshToGrid normalize in TopologyBuilder, and the point builders initialize fresh headers via GridData::init. Regression tests run grids 0 and 1 of a merged two-grid handle through both tools; verified failing before the fix with exactly the two throws you predicted.

🚩 issue: This long-standing constructor previously did a single header read; it now does one cudaMemcpyAsync + full cudaStreamSynchronize per grid header inside validGridChainCount. cuda::mergeGridHandles ends by constructing exactly this handle, so merging hundreds of grids now issues hundreds of serialized 672-byte D2H copies, each draining the stream, where the old code did one memcpy plus one kernel.

Two shapes that would fix it, either of which I'd be happy with: (a) since the validation walk already copies every full GridData header to the host, accumulate mMetaData directly in the walk — that deletes the scratch allocation, the cpyGridHandleMeta<<<1,1>>> launch, the second D2H copy, and the final sync in both constructors, so the validation replaces the old parse machinery instead of adding to it (the round trips stay O(N), but the whole second phase disappears); or (b) move the validation into a single device-side kernel with one status readback, restoring O(1) round trips for the multi-grid case.

Fixed in 0f4395d with shape (b) plus the deletion from (a): one host read of the head header (still needed to size the metadata scratch and bound a forged mGridCount before allocating), then a single kernel that validates the chain and fills the metadata scratch, one readback, one sync. So the whole second phase — the cpyGridHandleMeta launch, its D2H copy, and the final sync — is gone from both constructors, and constructing the handle mergeGridHandles returns costs two round trips regardless of grid count.

💅 polish: This body is a token-for-token copy of grid() and the dual-space deviceGrid() — the same null/index/gridType checks and util::PtrAdd, differing only in the base pointer (mBuffer.data() vs mBuffer.deviceData()). A private ungated helper taking the base pointer (e.g. gridAt<ValueT>(const void* base, uint32_t n)) would serve all three, so a future change to the lookup contract doesn't need three edits — this inline copy sits far from the two out-of-line definitions and would be the one that gets missed.

Fixed in e86e55e — a private gridAt<ValueT>(base, n) now backs grid() and both deviceGrid() families.

💡 suggestion: Both copy() overloads carry an identical if constexpr guard and multi-line static_assert, and this overload's single-space branch just discards other and forwards to copy<OtherBufferT>() — which re-fires the same assert, so today every misuse emits the diagnostic twice. I believe the guard can live solely in the no-arg copy() with identical diagnostics for every (BufferT, OtherBufferT) combination. This matters for part 2: when cross-space transfers land, the "not supported yet" condition and message get relaxed, and with two copies of the guard the two spellings can silently drift to accepting different type combinations.

Fixed in e86e55e — the guard lives solely in the no-arg copy(); the pool overload forwards its single-space branch there uncommented, so a misuse diagnoses once and the two spellings cannot drift when cross-space transfers relax the condition.

💡 suggestion: Could we move BufferHasDeviceSingle/BufferHasHostSingle next to the BufferTraits primary in HostBuffer.h (or a small shared traits header)? They aren't GridHandle-specific — they're companions to the trait protocol itself — and there's a concrete second consumer lined up: VoxelBlockManagerHandle needs exactly the same dispatch to map deviceFirstLeafID()/deviceJumpMap() onto data() for single-space buffers (the VBM follow-up to this PR under #2232), and it shouldn't have to include GridHandle.h, or duplicate the detectors, to get it.

Fixed in e86e55e — both detectors now sit beside the BufferTraits primary in HostBuffer.h, so VoxelBlockManagerHandle gets them without GridHandle.h.

💡 suggestion: This @note is effectively the definition of a "single-space buffer concept" — it lists exactly the members a buffer must provide for hasDeviceSingle to be honored. Since other handle types will consume the same contract (VoxelBlockManagerHandle is next, per the #2232 plan), could we phrase it as such — name the concept, and state that any consumer of hasDeviceSingle may rely on exactly this interface? That lets the follow-up PRs cite it instead of reverse-engineering the GridHandle constructor.

Fixed in e86e55e — the @note now defines the single-space device-buffer concept and enumerates the exact interface a consumer of hasDeviceSingle may rely on. It also got tighter while writing it down: the metadata scratch now allocates through resource() as a cuda::Buffer, so the constructor shape is no longer part of the contract — a conforming buffer never needs to be constructible by a consumer.